.. SPDX-License-Identifier: GPL-2.0 or GPL-3.0
.. Copyright © 2019 Ariadne Devos

Failbit: encoding failure in an integer
=======================================

The irrevocable failbit of an integer, if used, keeps tracks
of failures. It reserves the most-significant bit of a variable
for itself, the others are left intact. It remembers if there
had been at least a single failure.

(Header: <sHT/logic/failbit.h>. These machines are always marked
with `sHT_with_failbit`.)

This little, one-bit state machine[#f1]_ is started with
`var = sHT_success(T, var)`. It can be moved into the failure
state with `sHT_fail_if(T, var, condition)`. Once there,
it is stuck until the machine is reset.

The machine's state can be queried by `sHT_good(T, var)` and
`sHT_bad(T, var)`, these may give speculatively incorrect
results. The unused bits can be extracted by `sHT_fail_value`,
the state machine is oblivious to their meaning.

But these bits must not interfere with the machine's working;
`failbit_clean(T, value)` := `0 <= value < failbit_limit(T)`
is a necessary and sufficient condition.

Compatible APIs
---------------

Many lexers <sHT/lex/...>, arithmetic overflow tracking
<sHT/logic/arithmetic.h>.

.. rubric:: footnotes

.. [#f1] A formulation involving Monad transformers and Monoid
would be most welcome.
